 READ_ACE.TXT        Advantage Client Engine API            7.0
==============      =============================      =============

This READ_ACE.TXT file contains information about the Advantage
Client Engine API that may not be in the Advantage Help file.


Contents:
==========
1. Effects of Upgrading
2. Effects of Upgrading from a Version Prior to v6.2
3. Important Notes
4. What's New in v7.0


1. Effects of Upgrading
========================

The following Advantage functionality changes may affect your
applications if you upgrade to version 7.0 of the Advantage
Client Engine API.

a) As of v7.0, the maximum user group name length in a data dictionary
   is limited to 100 characters. In versions prior to 7.0, the limit
   was 200 characters.

b) If issuing SQL UPDATE or INSERT statements, there are DBF numeric
   fields involved in the update/insert, and the values specified for
   the numeric fields have more precision (decimal digits) than the
   numeric field definition, the v7.0 SQL engine no longer truncates
   the extra decimal digits while returning a data truncation error
   (Native Error 2102). Instead with v7.0, the value is rounded and
   truncated using the standard method (5 and above are rounded up)
   and no error is returned.

c) In v7.0, SQL support was added for scripts of semicolon delimited
   SQL statements. For applications that build SQL statements
   dynamically and allow user input to affect the statement that is
   generated, this can generate some security issues. Since old
   (pre-7.0) clients can be used with a 7.0 server, the installing of
   the new 7.0 server brings these new security risks. See the
   "Scripts" topic in the "Advantage SQL" | "Supported Grammar" book in
   the Advantage Help file for details.

d) In versions prior to 7.0, a bug let users add views that had ORDER
   BY clauses. A view cannot have an ORDER BY clause. This bug has been
   fixed, so creating views with an ORDER BY clause is no longer
   allowed. Existing views will continue to work, but if you try to add
   a new view, or modify an existing view that has an ORDER BY clause,
   the operation will fail.

e) In versions prior to 7.0, when executing stored procedures, the
   current user's access rights to tables or views were checked when
   tables or views were used in the stored procedures. An access
   permission error was returned if current user did not have
   sufficient access to tables or views used in the stored procedure.
   This behavior was inconsistent with the industry standard. Advantage
   v7.0 will no longer check current user's access rights to tables or
   views when they are used in the stored procedure.

f) DBF tables with memo or blob fields that are newly encrypted (where
   all records in the table are encrypted) using a 7.0 server and
   client will not be backwards compatible with pre-7.0 clients and
   servers because memo and blob data in DBF tables get encrypted in
   Advantage 7.0.


g) Fixed many Advantage Client Engine API prototype mistakes in
   ace32.bas. Specifically, many ByRef/ByVal parameter marshalling
   mistakes were fixed.

h) The AdsCheckExistence API has been enhanced when it is used on an
   Internet connection. In previous releases, the API always returned
   true on Internet connections regardless of the actual file
   existence. In the 7.0 release, the API may return true or false
   depending on the conditions described in the Help file
   documentation. See the AdsCheckExistence topic in the Advantage Help
   file for details.

i) Prior to v7.0, the default installation directory for the Advantage
   Client Engine API for Windows was "c:\ads\acesdk". With v7.0, the
   default installation directory has changed to "c:\Program
   Files\Extended Systems\Advantage\acesdk" to become more in line with
   most other software installs as well as to come in line with the
   Extended Systems corporate standard.


2. Effects of Upgrading from a Version Prior to v6.2
=====================================================

In addition to the effects of upgrading from version 6.2 of Advantage
mentioned in the section above, the following Advantage functionality
changes may affect your applications if you upgrade to version 7.0
of Advantage from a version of Advantage prior to v6.2.

a) The Advantage Expression Engine will now return a 3?01 error if a
   record filter or index expression contains an extra comma or right
   paren and has any other characters following that extra character.
   For example, the following expressions are now illegal: "lastname ,
   firstname", "left( 'extra paren', 10 ))", and "lastname, Advantage
   rules baby". Prior to v6.2, those expressions would have not
   returned an error and everything after the comma or right paren
   would have been ignored. Any existing applications that are
   mistakenly using a bad expression may start getting 3?01 errors if
   upgrading to v6.2 or greater.

b) Index creations will now return a 7089 error if they are cancelled.
   Prior to v6.2, a cancelled index creation would not cause the
   index creation operation to return an error. If your application
   provides index cancellation functionality you will need to address
   each instance and modify the source to correctly handle an error
   code (or exception if using the Advantage TDataSet Descendant) being
   returned from the index creation call.

c) A bug was fixed that affects the record position after the deletion
   of a record when a descending index is active (or the DESC keyword
   is used in an SQL statement). In versions prior to 6.2, after a
   record was deleted when a descending index was active, it was
   possible for the record pointer to jump to the last record in the
   dataset. This behavior has been fixed. Applications that expect the
   previous behavior may need to be modified.

d) When executing a CREATE TABLE statement, the column-level
   constraints can only be specified if the statement is executed by
   the dictionary administrator (ADSSYS) account on a database
   connection. The table created will be part of the database defined
   in the data dictionary. An error will be returned if a column-level
   constraint is specified and the statement is executed to create a
   free table. In versions prior to 6.2, the column-level constraints
   are incorrectly ignored when the CREATE TABLE statement is executed
   to create a free table. See the Advantage SQL Help documentation
   located in the Advantage.hlp Help file for additional information on
   creating database table and creating free table.

e) PRIMARY KEY syntax support was added in v6.2 to CREATE TABLE
   and ALTER TABLE statements. Therefore, any existing SQL statements
   that contain the words PRIMARY or KEY as identifiers will need
   to have double quotes added around them since they are now
   reserved key words.

f) If a v6.2 or greater client is used to update the user or user group
   permissions in a data dictionary, the data dictionary will be
   upgraded to a new internal version that indicates the data
   dictionary has support for additional user permissions. The new
   data dictionary version is compatible with previous clients for
   regular user access, but it is not compatible for administrative
   (ADSSYS user) access with older clients. In other words, pre-6.2
   clients will not be able to connect to this data dictionary as the
   ADSSYS user for administrative use.

g) Advantage versions 6.2 and greater use the WinHelp 2000 Windows Help
   file format. Advantage installs the RoboEx32.dll file in order to
   make this Help system functional. If RoboEx32.dll is not correctly
   installed into the Advantage Help file directory or does not exist
   in your system path, you will get the following error, "Cannot find
   or load the file RoboEx32.dll. This file should be copied to
   C:\WINDOWS\SYSTEM or a directory in your PATH."

h) A few Advantage Expression Engine error codes (3000 class errors)
   were changed in v6.2 to a more accurate 3000 class error code. If
   you were trapping exceptions or the like for these specific error
   codes, you may need to modify your code to trap for an updated 3xxx
   error code:
      - 3415: Invalid field type found in "is expression valid"
              function expression
      - 3409: Unsupported data type in function parameter in "is
              expression valid" function expression

i) If performing an AdsCopyTable operation on an ADT table, and that
   ADT table contains an AutoIncrement field, the AutoIncrement values
   will be preserved in the destination table. That is, the new records
   in the destination table will have the same values in the
   AutoIncrement column as those records in the source table. The next
   available AutoIncrement value will also be identical in the source
   and destination tables. Prior to v6.2, the records in the
   destination table would not maintain the AutoIncrement values.

j) AdsCopyTable AdsConvertTable, and AdsCopyTableContents will now copy
   records to the destination table in indexed order if an index handle
   is passed for the first parameter. Prior to v6.2, it was illegal to
   pass an index handle to these functions.

k) The SQL scalar functions SPACE, LEFT, and RIGHT were updated in v6.2
   to return a value that is the length specified. In previous
   versions, SPACE() always produced a value of 1024 bytes. LEFT() and
   RIGHT() would return a value the length of the given string
   parameter rather than the given length.

l) Advantage products for the Microsoft Windows operating system were
   modified in v6.2 to use 80-bit precision during floating point
   operations. In the past they used 64-bit precision. This may cause
   slight changes in floating point operations, but in general should
   result in more accurate results.

m) The Advantage Internet Server (AIS) has been integrated into the
   Advantage Database Server as of version 6.1. You no longer have to
   have a separate AIS.EXE application running to manage your Internet
   connections. There are several effects when upgrading your
   application to use AIS embedded within the Advantage Database
   Server. These include:
   * You will need to designate the port that the Advantage Database
     Server will listen on for incoming Internet connections.
   * You must enable Internet access in the Advantage Data Dictionary.
   * Advantage clients no longer use AIS.INI to configure for the
     Internet server. The entire configuration is accomplished in the
     ADS.INI file.
   * You must use Advantage v6.1 clients or greater in order to access AIS.
     Versions 6.0 and older of Advantage clients do not support the AIS
     functionality that is incorporated into version 6.1 of the
     Advantage Database Server.
   See the "Advantage Internet Server" book within the Advantage
   Database Server Help file (Advantage.hlp) for details.

n) When using the Advantage Local Server, the thread that calls and
   performs the user's registered callback function is the same thread
   that is actually performing the database operations (e.g., index
   creation and query execution). Because of this, it is important the
   application's registered callback function (via
   AdsRegisterCallbackFunction, AdsRegisterProgressCallback, or
   AdsRegisterSQLAbortFunc) be as efficient as possible. For example,
   the callback function should not block and wait for user input
   because that would stop the Advantage Local Server progress until
   the callback function returns. Prior to version 6.1, the callback
   function ran on a different thread so this was not an issue.

o) The Advantage SQL document, ADS_SQL.PDF, is obsolete as of v6.1 and
   is no longer installed with Advantage products. The information that
   was formerly within that PDF has been enhanced and is incorporated
   into the "Advantage SQL" book of the new Advantage master Help file,
   (Advantage.hlp or advantage.htm).

p) WINDOWS : All Advantage Help files are now installed into a common
   directory, C:\Program Files\Extended Systems\Advantage\Help. This
   allows all Advantage Help files to be accessed from a single
   "master" Advantage Help file, Advantage.hlp. The Advantage.hlp file
   also contains all Advantage information that is common to all (or
   nearly all) Advantage products.

q) As of v6.1, the SQL scalar functions soundex() and difference()
   were updated to conform to the standard definition. The soundex()
   function now returns the expected 4 digit phonetic code of the
   form <letter><digit><digit><digit>. The difference() function now
   returns an integer value in the range 0 to 4, where 4 indicates
   the closest phonetic match, and 0 indicates little or no phonetic
   match.

r) In Advantage versions prior to 6.1, when a table is requested to be
   open with read/write access, but where the table can only be opened
   with read-only access due to an OS file access restriction such as
   CD-ROM based tables or a data dictionary table access restriction,
   a 7013 error was returned at the table open time. In Advantage
   version 6.1 and greater, the table will be opened with read-only
   access in this scenario, and no error will be returned during the
   table open. A 5072 error will be returned if one attempts to update
   the data in the table, however.

s) The Advantage encryption in version 6.0 and greater of Advantage
   clients and servers uses a 160-bit encryption algorithm instead of
   the 40-bit encryption algorithm used in previous versions. Advantage
   version 6.0 and greater will also encrypt the memo and BLOB data in
   ADT tables if the table is completely encrypted. Because of these
   changes, if a table is encrypted with a password that is longer
   than 5 characters using Advantage version 6.0 or greater clients, or
   if a table is fully encrypted using Advantage version 6.0 or
   greater clients (regardless of the password length), the table is not
   backwards compatible with earlier versions (i.e., versions prior to
   6.0) of Advantage clients and servers. However, tables encrypted
   using earlier versions (i.e., versions prior to 6.0) of Advantage
   clients are fully compatible with Advantage version 6.0 and greater
   clients and servers.

t) Advantage Client Engine-based clients older than v2.5 will not be
   able to access encrypted tables with version 6.0 or greater of the
   Advantage Database Server. Use the release 6.0 or greater Advantage
   Client Engine-based clients with an Advantage 6.0 or greater server.

u) In releases prior to 6.0, you could specify a "tag" name that was
   different than the index file name when using AdsCreateIndex to
   create a non-compound index (i.e., a NTX or IDX index). This
   tag name would be used as the index name within the Advantage Client
   Engine until the index file was closed. When the index file was
   re-opened, the index name would be the base file name rather than
   the originally specified tag name. With v6.0, we changed it to be
   consistent and always use the base file name as the index name. A
   specified tag name will be ignored for non-compound index files.
   This change was necessary for Data Dictionary integrity.

v) If you are upgrading from a version prior to 2.5 and are using ADI
   indexes, you must reindex your indexes. It is not necessary to
   reindex if you are upgrading from version 2.5 or greater and/or are
   using CDX, IDX, or NTX indexes.

w) Encryption support within Advantage changed substantially in
   version 2.5 in order to improve security, performance, and data
   integrity. If you are using encryption in your application, and
   are upgrading from a version prior to v2.5, refer to the document
   "ENCRYPT.DOC" that is available for download from the Advantage
   Developer Zone web site <DevZone.AdvantageDatabase.com>. If you
   are upgrading from version 2.5 or greater, no issues related to
   encryption should affect you.


3. Important Notes
====================

a) SERVER COMPATIBILITY
   The Advantage Client Engine API v7.0 requires version 7.0
   or greater of the Advantage Local Server or the Advantage Database
   Server. If the Advantage Client Engine API attempts to connect with
   an older version of the server, it will generate an Advantage error.

b) SHUTTING DOWN YOUR APPLICATION
   Because of the server communication issues with the server, your
   Advantage Client Engine API application should include a call to
   AdsApplicationExit before the application exits and after it is
   finished with Advantage Client Engine calls. In addition,
   applications should call AdsThreadExit prior to returning from a
   thread.


4. What's New in v7.0
=============================

a) New functionality specific to the Advantage Client Engine API:

   * Added AdsResetConnection API to reset a connection by rolling back
     any uncommitted transactions, releasing any record locks, closing
     all open tables, closing open indexes, closing SQL statement
     information, closing open SQL cursors, and unloading all stored
     procedure modules.

   * Added AdsGetKeyColumn API to retrieve key column information from
     a table or cursor.

   * Changed AdsDDRemoveTable to allow missing or corrupted tables to
     be removed from a data dictionary.

   * Added support to undelete all records marked for deletion in an
     ADT table via the AdsRecallAllRecords API.

   * Added functionality to AdsCopyTableContents to allow an ADT
     timestamp field to be truncated into a date or time field during
     the copy of the table contents.

b) New Advantage functionality associated with the SQL engine:

   * Added ability to execute SQL scripts via a semicolon delimited
     list of SQL statements. Not only is executing scripts in this
     fashion convenient, it can also increase performance, as the
     statements are sent to the server in one request and processed
     individually by the server. In low bandwidth situations, or when
     executing a large script, this can result in a dramatic speed
     increase. See the "Scripts" topic in the "Advantage SQL" |
     "Supported Grammar" book in the Advantage Help file for details.

   * Added transaction syntax support. BEGIN TRANSACTION, COMMIT WORK,
     ROLLBACK WORK, and SET TRANSACTION statements are now supported.

   * Added database permission GRANT and REVOKE statements.

   * Added CREATE DATABASE and CREATE TRIGGER statements.

   * All data dictionary metadata is now accessible through SQL system
     tables and modifiable through system stored procedures. See the
     "Advantage SQL" | "System Views" book in the Advantage Help file
     for details.

   * Added CAST scalar for precision data type conversions.

   * Improved RAND scalar so that the number produced exhibits a
     better "random" behavior.

   * Added a virtual system table named iota. Iota is a table
     with one logical (SQL_BIT) column named "iota" and has a single
     row in the table with a NULL value in the "iota" column. The main
     purpose of the IOTA table is to provide an efficient method for
     evaluating an SQL expression on the server.

   * Improved performance of some SQL operations that require temporary
     sort files with larger data sets. For example, GROUP BY statement
     performance may be more than 10 times faster on data sets of 1
     million records and larger. In addition to GROUP BY statements,
     this can improve the speed of UNION, DISTINCT, and ORDER BY
     operations.

c) Miscellaneous new functionality:

   * Added a highly optimized Full Text Search engine. It is possible
     to search character, memo, and BLOB data using intuitive search
     phrases constructed of words and logical operators. See the "Full
     Text Search" topic in the Help file for details.

   * Added support for compression of all network communications
     between the client and the server. By default, compression is
     only turned on for connections made over the Internet. See the
     "Communications Compression" topic in the Advantage Help file
     for details and to determine if turning on compression will help
     your application's performance.

   * Added support for triggers. A trigger is a piece of code (similar
     to a stored procedure) that is executed on the server in response
     to an insert, update, or delete operation. Triggers can provide a
     very powerful means to maintain business rules at the database
     level.

   * Improved the performance of various database operations. For
     example, one should expect performance improvements of 10% and
     greater with insert/append operations, operations involving
     Advantage Optimized Filters, and deleting of records when the
     table contains one or more memo/BLOB fields.

   * When creating new indexes on a table with many records or when
     performing a reindex operation on a table with many records, the
     creation of that index will be much faster in 7.0 than earlier
     versions of Advantage Database Server. On tables with fewer than
     100,000 records, the performance improvement may not be
     significant. Tables with more than 100,000 records can expect up
     to a 50% performance increase. Table with multiple millions of
     records can expect even better performance increases, perhaps as
     much as 300% faster. Increasing the Advantage Database Server
     SORT_BUFFER configuration value can lead to even larger index
     creation performance increases with very large tables.

   * Added database (Advantage Data Dictionary) upgrade functionality.
     This functionality allows developers to ship version "A" of a
     database defined in a data dictionary, then later ship version "B"
     of the data dictionary. Functionality exists to compare Advantage
     Data Dictionaries and generate SQL upgrade scripts to "upgrade"
     one data dictionary to be structurally the same as a second data
     dictionary.

   * Added various Advantage Extended Procedure (AEP) Enhancements. A
     new AEP interface has been developed, which includes the following
     features:
      - AEP is passed an active connection handle, as opposed to a
        username and password. This active connection handle can be
        used to perform all data operations; no additional
        connections are required.
      - AEPs can be called inside a transaction, and all operations
        performed in the AEP using the active connection handle passed
        to the AEP are included in the context of the transaction.
      - Input and output parameters are passed through the virtual
        tables __input and __output. No more parsing of input/output
        table paths is necessary.
      - An additional connection to read the input and output tables
        is no longer necessary.
      - An in-memory table (__error) can be used to return
        descriptive error messages to the client application.
      - The number of rows affected can be returned and used from the
        client application just like it can with traditional SQL
        INSERT/UPDATE/DELETE statements.
      - New AEPs do not check user privileges when executing, which
        allows you to hide tables from the user(s), but allow access
        and modifications to those tables through AEPs that you
        control.
      - A combination of several of the above new features result in
        overall better AEP performance than with earlier versions.

   * Added new Money field data type for ADTs. This BCD-like field
     allows for currency data stored internally as a 64-bit integer,
     with 4 implied decimal digits from -922,337,203,685,477.5807 to
     +922,337,203,685,477.5807. No precision will be lost when doing
     calculations involving this data type.

   * Added support for DBF memo and BLOB data encryption. If all
     records in a DBF table are encrypted, all fields in the table will
     be encrypted, including and memo and binary fields.

   * Added support for fixed and keyset-driven Advantage Optimized
     Filter (AOF) types in addition to the existing dynamic type when
     used with the Advantage Database Server. These different AOF types
     provide different levels of filter membership when used with
     the Advantage Database Server (not Advantage Local Server). With
     dynamic AOFs, filter membership is affected by modifications all
     users make to record data. With keyset-driven AOFs, filter
     membership is only affected by updates from the filter owner (the
     table instance that set the filter). Updates made by other users
     will not affect a record's membership in the filter. With fixed
     AOFs, filter membership does not change. If other users modify
     records, they will always remain visible within this fixed filter,
     even if the changes have modified field values such that the
     record no longer passes the original filter expression.

